home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / u_man / cat3 / Tk / getbitmap.z / getbitmap
Encoding:
Text File  |  2002-10-03  |  14.2 KB  |  265 lines
  1.  
  2.  
  3.  
  4. TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      Tk_GetBitmap, Tk_DefineBitmap, Tk_NameOfBitmap, Tk_SizeOfBitmap,
  10.      Tk_FreeBitmap, Tk_GetBitmapFromData - maintain database of single-plane
  11.      pixmaps
  12.  
  13. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  14.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  15.  
  16.      Pixmap
  17.      TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _t_k_w_i_n, _i_d))))
  18.  
  19.      int
  20.      TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp((((_i_n_t_e_r_p, _n_a_m_e_I_d, _s_o_u_r_c_e, _w_i_d_t_h, _h_e_i_g_h_t))))
  21.  
  22.      Tk_Uid
  23.      TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p))))
  24.  
  25.      TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p, _w_i_d_t_h_P_t_r, _h_e_i_g_h_t_P_t_r))))
  26.  
  27.      TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp((((_d_i_s_p_l_a_y, _b_i_t_m_a_p))))
  28.  
  29. AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  30.      Tcl_Interp      *_i_n_t_e_r_p     (in)      Interpreter to use for error
  31.                                            reporting.
  32.  
  33.      Tk_Window       _t_k_w_i_n       (in)      Token for window in which the
  34.                                            bitmap will be used.
  35.  
  36.      Tk_Uid          _i_d          (in)      Description of bitmap;  see below
  37.                                            for possible values.
  38.  
  39.      Tk_Uid          *_n_a_m_e_I_d     (in)      Name for new bitmap to be defined.
  40.  
  41.      char            *_s_o_u_r_c_e     (in)      Data for bitmap, in standard bitmap
  42.                                            format.  Must be stored in static
  43.                                            memory whose value will never
  44.                                            change.
  45.  
  46.      int             _w_i_d_t_h       (in)      Width of bitmap.                   |
  47.  
  48.      int             _h_e_i_g_h_t      (in)      Height of bitmap.                  |
  49.  
  50.      int             *_w_i_d_t_h_P_t_r   (out)     Pointer to word to fill in with    |
  51.                                            _b_i_t_m_a_p's width.
  52.  
  53.      int             *_h_e_i_g_h_t_P_t_r  (out)     Pointer to word to fill in with    |
  54.                                            _b_i_t_m_a_p's height.
  55.  
  56.      Display         *_d_i_s_p_l_a_y    (in)      Display for which _b_i_t_m_a_p was
  57.                                            allocated.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
  71.  
  72.  
  73.  
  74.      Pixmap          _b_i_t_m_a_p      (in)      Identifier for a bitmap allocated
  75.                                            by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
  76.  
  77.  
  78. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  79.      These procedures manage a collection of bitmaps (one-plane pixmaps) being
  80.      used by an application.  The procedures allow bitmaps to be re-used
  81.      efficiently, thereby avoiding server overhead, and also allow bitmaps to
  82.      be named with character strings.
  83.  
  84.      TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp takes as argument a Tk_Uid describing a bitmap.  It returns
  85.      a Pixmap identifier for a bitmap corresponding to the description.  It
  86.      re-uses an existing bitmap, if possible, and creates a new one otherwise.
  87.      At present, _i_d must have one of the following forms:
  88.  
  89.      @@@@_f_i_l_e_N_a_m_e           _F_i_l_e_N_a_m_e must be the name of a file containing a
  90.                          bitmap description in the standard X11 or X10 format.
  91.  
  92.      _n_a_m_e                _N_a_m_e must be the name of a bitmap defined previously
  93.                          with a call to TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp.  The following names
  94.                          are pre-defined by Tk:
  95.  
  96.                          eeeerrrrrrrroooorrrr       The international "don't" symbol:  a
  97.                                      circle with a diagonal line across it.
  98.  
  99.                          ggggrrrraaaayyyy55550000      50% gray: a checkerboard pattern where
  100.                                      every other bit is on.
  101.  
  102.                          ggggrrrraaaayyyy22225555      25% gray: a pattern where 25% of the bits
  103.                                      are on, consisting of all the bit
  104.                                      positions that can be reached by a chess
  105.                                      knight starting at (0,0).
  106.  
  107.                          hhhhoooouuuurrrrggggllllaaaassssssss   An hourglass symbol.
  108.  
  109.                          iiiinnnnffffoooo        A large letter ``i''.
  110.  
  111.                          qqqquuuueeeesssstttthhhheeeeaaaadddd   The silhouette of a human head, with a
  112.                                      question mark in it.
  113.  
  114.                          qqqquuuueeeessssttttiiiioooonnnn    A large question-mark.
  115.  
  116.                          wwwwaaaarrrrnnnniiiinnnngggg     A large exclamation point.
  117.  
  118.      Under normal conditions, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp returns an identifier for the
  119.      requested bitmap.  If an error occurs in creating the bitmap, such as
  120.      when _i_d refers to a non-existent file, then NNNNoooonnnneeee is returned and an error
  121.      message is left in _i_n_t_e_r_p->_r_e_s_u_l_t.
  122.  
  123.      TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp associates a name with in-memory bitmap data so that the
  124.      name can be used in later calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.  The _n_a_m_e_I_d argument
  125.      gives a name for the bitmap;  it must not previously have been used in a
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
  137.  
  138.  
  139.  
  140.      call to TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp.  The arguments _s_o_u_r_c_e, _w_i_d_t_h, and _h_e_i_g_h_t
  141.      describe the bitmap.  TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp normally returns TCL_OK;  if an
  142.      error occurs (e.g. a bitmap named _n_a_m_e_I_d has already been defined) then
  143.      TCL_ERROR is returned and an error message is left in _i_n_t_e_r_p->_r_e_s_u_l_t.
  144.      Note:  TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp expects the memory pointed to by _s_o_u_r_c_e to be
  145.      static:  TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp doesn't make a private copy of this memory, but
  146.      uses the bytes pointed to by _s_o_u_r_c_e later in calls to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
  147.  
  148.      Typically TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp is used by ####iiiinnnncccclllluuuuddddeeee-ing a bitmap file directly
  149.      into a C program and then referencing the variables defined by the file.
  150.      For example, suppose there exists a file ssssttttiiiipppp....bbbbiiiittttmmmmaaaapppp, which was created
  151.      by the bbbbiiiittttmmmmaaaapppp program and contains a stipple pattern.  The following code
  152.      uses TTTTkkkk____DDDDeeeeffffiiiinnnneeeeBBBBiiiittttmmmmaaaapppp to define a new bitmap named ffffoooooooo:
  153.           Pixmap bitmap;
  154.           #include "stip.bitmap"
  155.           Tk_DefineBitmap(interp, Tk_GetUid("foo"), stip_bits,
  156.                           stip_width, stip_height);
  157.           ...
  158.           bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("foo"));
  159.      This code causes the bitmap file to be read at compile-time and
  160.      incorporates the bitmap information into the program's executable image.
  161.      The same bitmap file could be read at run-time using TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp:
  162.           Pixmap bitmap;
  163.           bitmap = Tk_GetBitmap(interp, tkwin, Tk_GetUid("@stip.bitmap"));
  164.      The second form is a bit more flexible (the file could be modified after
  165.      the program has been compiled, or a different string could be provided to
  166.      read a different file), but it is a little slower and requires the bitmap
  167.      file to exist separately from the program.
  168.  
  169.      TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp maintains a database of all the bitmaps that are currently
  170.      in use.  Whenever possible, it will return an existing bitmap rather than
  171.      creating a new one.  This approach can substantially reduce server
  172.      overhead, so TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp should generally be used in preference to Xlib
  173.      procedures like XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee.
  174.  
  175.      The bitmaps returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp are shared, so callers should never
  176.      modify them.  If a bitmap must be modified dynamically, then it should be
  177.      created by calling Xlib procedures such as XXXXRRRReeeeaaaaddddBBBBiiiittttmmmmaaaappppFFFFiiiilllleeee or
  178.      XXXXCCCCrrrreeeeaaaatttteeeePPPPiiiixxxxmmmmaaaapppp directly.
  179.  
  180.      The procedure TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp is roughly the inverse of TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
  181.      Given an X Pixmap argument, it returns the _i_d that was passed to
  182.      TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp when the bitmap was created.  _B_i_t_m_a_p must have been the
  183.      return value from a previous call to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
  184.  
  185.      TTTTkkkk____SSSSiiiizzzzeeeeOOOOffffBBBBiiiittttmmmmaaaapppp returns the dimensions of its _b_i_t_m_a_p argument in the
  186.      words pointed to by the _w_i_d_t_h_P_t_r and _h_e_i_g_h_t_P_t_r arguments.  As with
  187.      TTTTkkkk____NNNNaaaammmmeeeeOOOOffffBBBBiiiittttmmmmaaaapppp, _b_i_t_m_a_p must have been created by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.
  188.  
  189.      When a bitmap returned by TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp is no longer needed, TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp
  190.      should be called to release it.  There should be exactly one call to
  191.      TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp for each call to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp.  When a bitmap is no longer
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp((((3333TTTTkkkk))))
  203.  
  204.  
  205.  
  206.      in use anywhere (i.e. it has been freed as many times as it has been
  207.      gotten) TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp will release it to the X server and delete it from
  208.      the database.
  209.  
  210.  
  211. BBBBUUUUGGGGSSSS
  212.      In determining whether an existing bitmap can be used to satisfy a new
  213.      request, TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp considers only the immediate value of its _i_d
  214.      argument.  For example, when a file name is passed to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp,
  215.      TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp will assume it is safe to re-use an existing bitmap created
  216.      from the same file name:  it will not check to see whether the file
  217.      itself has changed, or whether the current directory has changed, thereby
  218.      causing the name to refer to a different file.
  219.  
  220.  
  221. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  222.      bitmap, pixmap
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.